<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<meta name="description" content="This document catalogs a set of recommended practices for composing documents in AsciiDoc.">
<meta name="author" content="Dan Allen">
<title>AsciiDoc Recommended Practices</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment @import statement to use as custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
:not(pre)>code.nobreak{word-wrap:normal}
:not(pre)>code.nowrap{white-space:nowrap}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}
pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}
pre.pygments .lineno::before{content:"";margin-right:-.125em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="article">
<div id="header">
<h1>AsciiDoc Recommended Practices</h1>
<div class="details">
<span id="author" class="author">Dan Allen</span><br>
<span id="revnumber">version 1.0-HEAD,</span>
<span id="revdate">2016-12-21</span>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This document catalogs a set of recommended practices for composing documents in AsciiDoc.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">DRAFT</div>
<div class="paragraph">
<p>This document is only a rough draft.
These recommendations are not doctrine and are subject to change.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>AsciiDoc offers multiple ways to accomplish the same thing, and is often very lenient with the syntax.
This guide helps bring consistency to your documents that will maximize efficiency, improve readability and minimize maintenance.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_document_extension">Document extension</h2>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc doesn&#8217;t care which extension you use.
GitHub supports the extensions <code>.asciidoc</code>, <code>.adoc</code> and <code>.asc</code>.</p>
</div>
<div class="paragraph">
<p><code>.adoc</code> seems to be the most often used extension and the one we prefer.
It does not conflict with other well known applications, is distinct, and not excessively long (like <code>.asciidoc</code>).
It also reads as &#8220;a doc&#8221;.
Our recommendation, therefore, is to use <code>.adoc</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
We strongly recommend <em>against</em> using the <code>.asc</code> extension.
The connection to AsciiDoc isn&#8217;t immediately obvious and it gets falsely identified as a PGP file on Linux.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_one_sentence_per_line">One Sentence Per Line</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Don&#8217;t wrap text at a fixed column width.
Instead, put each sentence on its own line, a technique called <em>sentence per line</em>.
This technique is similar to how you write and organize source code.
The result can be spectacular.</p>
</div>
<div class="paragraph">
<p>Here are some of the advantages of using the sentence per line style:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It prevents reflows (meaning a change early in the paragraph won&#8217;t cause the remaining lines in the paragraph to reposition).</p>
</li>
<li>
<p>You can easily swap sentences.</p>
</li>
<li>
<p>You can easily separate or join paragraphs.</p>
</li>
<li>
<p>You can comment out sentences or add commentary to them.</p>
</li>
<li>
<p>You can spot sentences which are too long or sentences that vary widely in length.</p>
</li>
<li>
<p>You can spot redundant (and thus mundane) patterns in your writing.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>We picked up this idea from the writing guide in the <a href="https://neo4j.com/docs/2.2.8/community-docs.html#_writing">Neo4j documentation</a>.
However, it seems like the idea dates back a discovery by Buckminster Fuller in the 1930s, who called it <a href="https://vanemden.wordpress.com/2009/01/01/ventilated-prose/">ventilated prose</a>.
The technique was also recommended in 2009 by Brandon Rhodes in a blog post about <a href="https://rhodesmill.org/brandon/2012/one-sentence-per-line/">Semantic Linefeeds</a>.</p>
</div>
<div class="paragraph">
<p>It&#8217;s important to note that this technique works because AsciiDoc doesn&#8217;t treat wrapped lines in prose as hard line breaks.
At least, it doesn&#8217;t show up that way to the reader.
The line breaks between contiguous lines of prose will not be visible in the rendered document (i.e., as the reader sees it).</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
While a single line break doesn&#8217;t appear in the output, two consecutive line breaks starts a new paragraph (or other block).
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_section_titles">Section Titles</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are three ways to define a section title.
These variants can be classified into two types of styles, <em>atx</em> and <em>setext</em> (historical names).
<strong>The asymmetric Atx-style is the style we recommend to define your section titles.</strong></p>
</div>
<div class="paragraph">
<div class="title">Atx-style</div>
<p>In the Atx-style, the section title is defined on a single line.
The section title begins with one or more equal characters (i.e., <code>=</code>) followed by a space and the section title.
The number of leading characters representing the depth.
The top-level section is reserved for the document title, so the first section in the document will have two leading characters.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>== First Section</pre>
</div>
</div>
<div class="paragraph">
<p>This example uses the asymmetric Atx-style.
It requires the least number of characters and it&#8217;s intuitive since the number of leading characters represents the heading level.</p>
</div>
<div class="paragraph">
<p>When using the HTML backend, this section title will be transformed into an h2 heading (likely wrapped in a section block for styling):</p>
</div>
<div class="literalblock">
<div class="content">
<pre>&lt;h2&gt;First Section&lt;/h2&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>The symmetric Atx-style bookends the section title between a matching pair of delimiters.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>== First Section ==</pre>
</div>
</div>
<div class="paragraph">
<p>While this syntax may look nicer to some, it requires twice the number of delimiters without adding any additional semantics.
Therefore, I consider it a waste of keystrokes and don&#8217;t recommend using it.
However, either of the Atx-style section titles are better than the Setext style.</p>
</div>
<div class="paragraph">
<div class="title">Setext</div>
<p>In the Setext-style, the section title is defined on two lines.
The second line is a string of characters that form an underline below the section title.
Here&#8217;s an example of a section title from above defined in the Setext-style.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>First Section
-------------</pre>
</div>
</div>
<div class="paragraph">
<p>Since the length of the line is determined by the number of characters in the section title, another dimension must be introduced to determine the level.
That dimension is the character used for the underline.
The characters used are (sorted from document title to level 5 section) <code>=</code>, <code>-</code>, <code>~</code>, <code>^</code>, and <code>+</code>.</p>
</div>
<div class="paragraph">
<p>I <em>strongly</em> recommend against using the Setext style for section titles.
Keeping the length of the underline in sync with the title length is an unnecessary task and time waster.
A more substantial reason is that the mapping between character and heading level is <strong>very</strong> difficult to remember and not obvious to new AsciiDoc adopters.
All in all, using Setext section titles is a <em>bad practice</em>.
<strong>Don&#8217;t use them!</strong></p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
The recommendation is to use the asymmetric Atx-style for section titles.
It&#8217;s the most simple and intuitive method for writing, as well as for reading in the plain text (source) file.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_document_title">Document title</h3>
<div class="paragraph">
<p>Since the document title occurs only once in a document, I consider it acceptable (but strongly discouraged) to use the Setext style in this instance, so long as you <strong>also</strong> disable the compat-mode attribute (otherwise, it puts the processor into compat mode).</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Document Title
==============
Author Name &lt;author@example.org&gt;
:compat-mode!:</pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
You must explicitly disable compatibility mode (i.e., <code>compat-mode!</code>) in this case if you don&#8217;t want it enabled.
Compatibility mode is automatically enabled when using the Setext style document title.
See the <a href="migration.html">migration guide</a> for details.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Be sure to include your name immediately following the document title.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
AsciiDoc only supports an e-mail following the author line.
It does not support a personal URL.
Asciidoctor supports a raw URL as well as an inline link macro.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>It&#8217;s a good practice to also include a revision line following the author line.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Document Title
==============
Author Name &lt;author@example.org&gt;
v1.0, 2012-02-10
:compat-mode!:</pre>
</div>
</div>
<div class="paragraph">
<p>The version number is optional.
The revision line may consist of a date only.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Document Title
==============
Author Name &lt;author@example.org&gt;
2012-02-10
:compat-mode!:</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_delimited_blocks">Delimited Blocks</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Delimited blocks contain special text such as code listings, quotes, sidebar text, tables and so on.
As you may have guessed, they are bounded by a string of delimiters.
The delimiters are defined on a line by themselves.
The content goes in between the delimiter lines.
Here&#8217;s an example of a listing:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>----
$ asciidoctor -b html5 recommended-practices.adoc
----</pre>
</div>
</div>
<div class="paragraph">
<p>Delimited blocks require four or more repeating characters on a line by themselves to mark the boundary of the block.
The one exception is the open block, which only requires two <code>-</code> repeating characters.</p>
</div>
<div class="paragraph">
<p>You may be tempted to extend the line further, either to a predetermined length or to match the length of the content.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>-------------------------------------------------
$ asciidoctor -b html5 recommended-practices.adoc
-------------------------------------------------</pre>
</div>
</div>
<div class="paragraph">
<p><strong>Don&#8217;t do this!</strong></p>
</div>
<div class="paragraph">
<p>Maintaining long delimiter lines is <em>a colossal waste of time</em>, not to mention arbitrary and error prone.
I strongly urge you to <em>use the minimum number of characters necessary</em> to form a delimited block and move on to drafting the content.
The reader will never see these long strings of delimiters anyway since they are not carried over to the output (HTML, DocBook, etc).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
AsciiDoc does not enforce that the length of the line that opens the delimited block match the length of the line that closes the delimited block, but I think <em>it should</em>.
Asciidoctor enforces this requirement, so make sure they match!
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_document_attributes_i_e_variables">Document Attributes (i.e., Variables)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can save yourself a lot of typing by leveraging document attributes.
Document attributes promote frequently occurring references and phrases to the top of the document (or section).
You can declare information once by assigning it to an attribute, then refer to that attribute throughout the document.
In that sense, you can think of attributes like variables for AsciiDoc.</p>
</div>
<div class="paragraph">
<p>Storing information in attributes that you declare at the top of the document makes finding the information easy and saves you from having to update the information in multiple places (i.e., keeps the document DRY).
When you update the value of the attribute, the value will change everywhere in the document that attribute is referenced.</p>
</div>
<div class="sect2">
<h3 id="_dry_urls">DRY URLs</h3>
<div class="paragraph">
<p>A common use for attributes is to store URLs.
URLs frequently change, can be rather long, and often have special characters that need escaping.
All of these challenges are solved by declaring the URLs in attributes.</p>
</div>
<div class="paragraph">
<p>You simply assign the URL to a short, easy to remember attribute:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">:url-issues: https://github.com/asciidoctor/asciidoctor/issues</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then you reference this attribute whenever you want to use the URL in your document, such as to make a link:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">Submit bug fixes and feature requests to the {url-issues}[issue tracker].</code></pre>
</div>
</div>
<div class="paragraph">
<p>Since you may define attributes for many different things, it&#8217;s good to employ a system to keep them organized.
Let&#8217;s study one such system.</p>
</div>
</div>
<div class="sect2">
<h3 id="_attribute_groups">Attribute Groups</h3>
<div class="paragraph">
<p>If you define a lot of document attributes, the document header can get messy.
To keep it tidy, it&#8217;s a good idea to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Name related attributes using a common prefix (i.e., give them a namespace)</p>
</li>
<li>
<p>Group related attributes together underneath a banner</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, we recommend using either the prefix <code>url-</code> or <code>uri-</code> when declaring attributes that hold URL values.
This is done for several reasons:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>It communicates the type of value the attribute holds (e.g., <code>url-issues</code> is a URL for the issue tracker)</p>
</li>
<li>
<p>It avoids collisions with attributes used for other purposes (e.g., using <code>org</code> for the organization URL could collide with <code>org</code> used for the organization name)</p>
</li>
<li>
<p>It causes a code assist tool in an editor (such as text auto-completion) to naturally group related attributes (e.g., bring up a list of all URL attributes by typing <code>url-</code>)</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Grouping related attributes makes it easy to see where new attributes should be added, thus helping to keep the document header tidy.
It also opens the door for reorganizing the groups into separate files in the future.
Within a group, you might consider alphabetizing the attributes.
One exception to this rule is if an attribute references another attribute, in which case you have to define the attribute being referenced first.</p>
</div>
<div class="paragraph">
<p>Here are some of the banners we recommend for grouping related attributes in the document header:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>Metadata</em> - Attributes that define information that goes into the header of the output document for indexing</p>
</li>
<li>
<p><em>Settings</em> - Attributes that control built-in conversion and formatting behavior</p>
</li>
<li>
<p><em>Refs</em> - Attributes that are referenced in the content, such as URLs; prefix each attribute by its type to make auto-complete work nicer, such as <code>url-</code> for a URL.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can use whatever additional groups feel natural to you.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s how that looks when put these recommendations together:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">= Document Title
Author Name
// Metadata:
:description: The description of this page.
:keywords: writing, documentation, publishing
// Settings:
:icons: font
:idprefix:
:idseparator: -
// Refs:
:url-project: https://asciidoctor.org
:url-docs: {url-project}/docs
:url-issues:  https://github.com/asciidoctor/asciidoctor
:img-ci: https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_counters">Counters</h3>
<div class="paragraph">
<p>Counters are backed by document attributes.
Since they share the same global namespace as all other document attributes, it&#8217;s a good idea to apply a prefix to counter names to avoid collisions with other attributes.
For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{counter:cnt-step}</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_document_settings">Document settings</h3>
<div class="paragraph">
<p>Most document settings are controlled using attributes.
Document settings are configured using attribute entries immediately following the document title (without any blank lines in between).
There are several options of interest.</p>
</div>
<div class="paragraph">
<div class="title">Section numbering</div>
<p>You can enable numbering of sections using the <code>sectnums</code> attribute (off by default).</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:sectnums:</pre>
</div>
</div>
<div class="paragraph">
<div class="title">Document description</div>
<p>You can set the description of the document using the <code>description</code> attribute.
The description is included in the header of the document.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:description: This document catalogs a set of recommended practices for writing in AsciiDoc.</pre>
</div>
</div>
<div class="paragraph">
<p>You can break any <a href="user-manual.html#splitting-attribute-values-over-multiple-lines">attribute value across several lines</a> by ending the lines in a <code>\</code> preceded by a space.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:description: This document catalogs a set of recommended practices \
              for composing documents in AsciiDoc.</pre>
</div>
</div>
<div class="paragraph">
<p>You can use this text anywhere in the document by referencing it as an attribute.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{description}</pre>
</div>
</div>
<div class="paragraph">
<div class="title">Section title IDs and ID prefixes</div>
<p>IDs are generated for each section title by default.
The ID is generated from the section title, prefixed with an underscore (i.e., <code>_</code>) by default.
You can change the prefix using the <code>idprefix</code> attribute.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:idprefix: id_</pre>
</div>
</div>
<div class="paragraph">
<p>If you want to remove the prefix, assign it to an empty value:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:idprefix:</pre>
</div>
</div>
<div class="paragraph">
<p>To disable the auto-generation of section IDs, unset the <code>sectids</code> attribute:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:sectids!:</pre>
</div>
</div>
<div class="paragraph">
<div class="title">Table of contents</div>
<p>Set the <code>toc</code> attribute to activate an auto-generated table of contents at the top of the document:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:toc:</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_images_and_other_media">Images and Other Media</h2>
<div class="sectionbody">
<div class="paragraph">
<p>TODO</p>
</div>
<div class="paragraph">
<div class="title">Paths</div>
<p>don&#8217;t include the images directory in each image reference</p>
</div>
<div class="paragraph">
<div class="title">Block vs inline</div>
<p>&#8230;&#8203;</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_conditional_inclusion">Conditional Inclusion</h2>
<div class="sectionbody">
<div class="paragraph">
<p>TODO</p>
</div>
<div class="paragraph">
<p>how to use, reason for using</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_lists">Lists</h2>
<div class="sectionbody">
<div class="paragraph">
<div class="title">Unordered list markers</div>
<p>AsciiDoc supports both <code>*</code> (one or more) and <code>-</code> (only one) as markers for a top-level list item.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>* first
* second
* third</pre>
</div>
</div>
<div class="paragraph">
<p>or</p>
</div>
<div class="literalblock">
<div class="content">
<pre>- first
- second
- third</pre>
</div>
</div>
<div class="paragraph">
<p>However, the dash marker <em>cannot</em> be repeated when defining a list item.
This can lead to confusion since AsciiDoc increases the nesting level each time it encounters a <em>different</em> marker.
For instance, in the following case, the item that has an asterisk marker is <strong>nested</strong> inside the first item.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>- first
* nested item
- second
- third</pre>
</div>
</div>
<div class="paragraph">
<p>This nesting rule is true even when the number of asterisks seems to indicate the level:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>*** first
* nested item
*** second
*** third</pre>
</div>
</div>
<div class="paragraph">
<p><em>Yep, that&#8217;s right, the second list item is nested inside the first list item.</em></p>
</div>
<div class="paragraph">
<p>If you stick to convention, the number of asterisks <em>can</em> represent the nesting level:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>* first
** nested item
* second
* third</pre>
</div>
</div>
<div class="paragraph">
<p>Now <strong>that&#8217;s</strong> intuitive.</p>
</div>
<div class="paragraph">
<p>I strongly recommend using the asterisk marker if you are going to be using nested lists.</p>
</div>
<div class="paragraph">
<p>If you only have top-level list items, then using either marker is reasonable.
I may even recommend using the dash marker for lists that are not intended to have nested items and the asterisk marker for lists that do have nested items.
That way it&#8217;s easy to identify them as different types.</p>
</div>
<div class="paragraph">
<div class="title">Description lists</div>
<p>They exist!</p>
</div>
<div class="paragraph">
<div class="title">Separating lists</div>
<p>Adjacent lists sometimes like to fuse.
To force the start of a new list, offset the two lists by an empty line comment:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>* apples
* oranges
* bananas

//-

* carrots
* tomatoes
* celery</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_literal_text">Literal Text</h2>
<div class="sectionbody">
<div class="paragraph">
<p>TODO</p>
</div>
<div class="paragraph">
<p>backticks vs plus and passthough stuffs</p>
</div>
<div class="paragraph">
<p>recommendation for inline code quote char</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_tables">Tables</h2>
<div class="sectionbody">
<div class="paragraph">
<div class="title">Stacked cells</div>
<p>Leverage them, makes it easy to read</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 1.0-HEAD<br>
Last updated 2020-07-22 16:48:17 +0800
</div>
</div>
</body>
</html>